/**
 *       Copyright (c) 2012 Lukas Zaruba
 *
 *   This file is part of Robot Playground.
 *
 *   Robot Playground is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU Lesser General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   Robot Playground is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU Lesser General Public License for more details.
 *
 *   You should have received a copy of the GNU Lesser General Public License
 *   along with Robot Playground. If not, see <http://www.gnu.org/licenses/>.
 */
package net.zarubsys.robotplayground.core.modules;

import java.util.List;
import java.util.Set;

import net.zarubsys.robotplayground.core.Environment;
import net.zarubsys.robotplayground.core.device.IDevice;
import net.zarubsys.robotplayground.core.device.NullDevice;
import net.zarubsys.robotplayground.core.functions.FunctionDescriptor;

/**
 * IModule
 * 
 * Implement this interface if you want to create your own Module.
 * 
 * Do not forget to contribute it to the proper extension point. Consult 
 * the Developer's Guide for details.
 * 
 * Your implementation must provide public non-parametric constructor.
 * 
 * You might want to use prepared {@link AbstractModule} that takes care about
 * the calls dispatching.
 *
 * @author Lukas Zaruba, lukas.zaruba@gmail.com
 */
public interface IModule<D extends IDevice, C extends IModuleConfiguration> {
	
	/**
	 * This method gets invoked after the instantiation is finished.
	 * @param device an instance of the device based on the output of {@link #getRequiredDevice()}
	 * method.
	 * @param configuration an instance of configuration based on the type parameterization
	 * of your class.
	 * @param env common environment for all session objects in this session run.
	 */
	void init(D device, C configuration, Environment env);
	
	/**
	 * @return a set of all functions that are provided by this Module
	 */
	Set<FunctionDescriptor> getAllFunctions();
	
	/**
	 * This method might be called with parameters related to any function published
	 * using the {@link #getAllFunctions()} method.
	 * 
	 * @param functionName name of the function to be invoked
	 * @param values values passed to the function based on its prototype
	 * @return result of the call or null if the function is void
	 */
	Object callFunction(String functionName, List<Object> values);
	
	/**
	 * This method gets invoked after the execution has finished.
	 * Dispose all necessary resources.
	 */
	void close();
	
	/**
	 * @return id of this module
	 */
	String getId();
	
	/**
	 * @return id of the device required by this module.
	 * Use {@link NullDevice} if you don't need any.
	 */
	String getRequiredDevice();

}

